home *** CD-ROM | disk | FTP | other *** search
/ Aminet 15 / Aminet 15 - Nov 1996.iso / Aminet / dev / gcc / ixemsdk.lha / man / cat3 / getopt.0 < prev    next >
Text File  |  1996-09-02  |  6KB  |  132 lines
  1.  
  2. GETOPT(3)                  UNIX Programmer's Manual                  GETOPT(3)
  3.  
  4. NNAAMMEE
  5.      ggeettoopptt - get option character from command line argument list
  6.  
  7. SSYYNNOOPPSSIISS
  8.      ##iinncclluuddee <<uunniissttdd..hh>>
  9.  
  10.      _e_x_t_e_r_n _c_h_a_r _*_o_p_t_a_r_g_;
  11.      _e_x_t_e_r_n _i_n_t _o_p_t_i_n_d_;
  12.      _e_x_t_e_r_n _i_n_t _o_p_t_o_p_t_;
  13.      _e_x_t_e_r_n _i_n_t _o_p_t_e_r_r_;
  14.      _e_x_t_e_r_n _i_n_t _o_p_t_r_e_s_e_t_;
  15.  
  16.      _i_n_t
  17.      ggeettoopptt(_i_n_t _a_r_g_c, _c_h_a_r _* _c_o_n_s_t _*_a_r_g_v, _c_o_n_s_t _c_h_a_r _*_o_p_t_s_t_r_i_n_g)
  18.  
  19. DDEESSCCRRIIPPTTIIOONN
  20.      The ggeettoopptt() function incrementally parses a command line argument list
  21.      _a_r_g_v and returns the next _k_n_o_w_n option character.  An option character is
  22.      _k_n_o_w_n if it has been specified in the string of accepted option charac-
  23.      ters, _o_p_t_s_t_r_i_n_g.
  24.  
  25.      The option string _o_p_t_s_t_r_i_n_g may contain the following elements: individu-
  26.      al characters, and characters followed by a colon to indicate an option
  27.      argument is to follow.  For example, an option string "x" recognizes an
  28.      option ``--xx'', and an option string "x:" recognizes an option and argu-
  29.      ment ``--xx _a_r_g_u_m_e_n_t''. It does not matter to ggeettoopptt() if a following argu-
  30.      ment has leading white space.
  31.  
  32.      On return from ggeettoopptt(), _o_p_t_a_r_g points to an option argument, if it is
  33.      anticipated, and the variable _o_p_t_i_n_d contains the index to the next _a_r_g_v
  34.      argument for a subsequent call to ggeettoopptt().  The variable _o_p_t_o_p_t saves
  35.      the last _k_n_o_w_n option character returned by ggeettoopptt().
  36.  
  37.      The variable _o_p_t_e_r_r and _o_p_t_i_n_d are both initialized to 1.  The _o_p_t_i_n_d
  38.      variable may be set to another value before a set of calls to ggeettoopptt() in
  39.      order to skip over more or less argv entries.
  40.  
  41.      In order to use ggeettoopptt() to evaluate multiple sets of arguments, or to
  42.      evaluate a single set of arguments multiple times, the variable _o_p_t_r_e_s_e_t
  43.      must be set to 1 before the second and each additional set of calls to
  44.      ggeettoopptt(), and the variable _o_p_t_i_n_d must be reinitialized.
  45.  
  46.      The ggeettoopptt() function returns -1 when the argument list is exhausted, or
  47.      a non-recognized option is encountered.  The interpretation of options in
  48.      the argument list may be cancelled by the option `--' (double dash) which
  49.      causes ggeettoopptt() to signal the end of argument processing and returns -1.
  50.      When all options have been processed (i.e., up to the first non-option
  51.      argument), ggeettoopptt() returns -1.
  52.  
  53. DDIIAAGGNNOOSSTTIICCSS
  54.      If the ggeettoopptt() function encounters a character not found in the string
  55.      _o_p_t_a_r_g or detects a missing option argument it writes an error message
  56.      and returns `?' to the _s_t_d_e_r_r. Setting _o_p_t_e_r_r to a zero will disable
  57.      these error messages.  If _o_p_t_s_t_r_i_n_g has a leading `:' then a missing op-
  58.      tion argument causes a `:' to be returned in addition to suppressing any
  59.      error messages.
  60.  
  61.      Option arguments are allowed to begin with ``-''; this is reasonable but
  62.      reduces the amount of error checking possible.
  63.  
  64. EEXXTTEENNSSIIOONNSS
  65.      The _o_p_t_r_e_s_e_t variable was added to make it possible to call the ggeettoopptt()
  66.      function multiple times.  This is an extension to the IEEE Std1003.2
  67.      (``POSIX'') specification.
  68.  
  69. EEXXAAMMPPLLEE
  70.      extern char *optarg;
  71.      extern int optind;
  72.      int bflag, ch, fd;
  73.  
  74.      bflag = 0;
  75.      while ((ch = getopt(argc, argv, "bf:")) != -1)
  76.              switch(ch) {
  77.              case 'b':
  78.                      bflag = 1;
  79.                      break;
  80.              case 'f':
  81.                      if ((fd = open(optarg, O_RDONLY, 0)) < 0) {
  82.                              (void)fprintf(stderr,
  83.                                  "myname: %s: %s\n", optarg, strerror(errno));
  84.                              exit(1);
  85.                      }
  86.                      break;
  87.              case '?':
  88.              default:
  89.                      usage();
  90.      }
  91.      argc -= optind;
  92.      argv += optind;
  93.  
  94. HHIISSTTOORRYY
  95.      The ggeettoopptt() function appeared 4.3BSD.
  96.  
  97. BBUUGGSS
  98.      The ggeettoopptt() function was once specified to return EOF instead of -1.
  99.      This was changed by  to decouple ggeettoopptt() from _<_s_t_d_i_o_._h_>.
  100.  
  101.      A single dash ``-'' may be specified as an character in _o_p_t_s_t_r_i_n_g, howev-
  102.      er it should _n_e_v_e_r have an argument associated with it.  This allows
  103.      ggeettoopptt() to be used with programs that expect ``-'' as an option flag.
  104.      This practice is wrong, and should not be used in any current develop-
  105.      ment.  It is provided for backward compatibility _o_n_l_y. By default, a sin-
  106.      gle dash causes ggeettoopptt() to return -1.  This is, we believe, compatible
  107.      with System V.
  108.  
  109.      It is also possible to handle digits as option letters.  This allows
  110.      ggeettoopptt() to be used with programs that expect a number (``-3'') as an op-
  111.      tion.  This practice is wrong, and should not be used in any current de-
  112.      velopment.  It is provided for backward compatibility _o_n_l_y. The following
  113.      code fragment works in most cases.
  114.  
  115.            int length;
  116.            char *p;
  117.  
  118.            while ((c = getopt(argc, argv, "0123456789")) != -1)
  119.                    switch (c) {
  120.                    case '0': case '1': case '2': case '3': case '4':
  121.                    case '5': case '6': case '7': case '8': case '9':
  122.                            p = argv[optind - 1];
  123.                            if (p[0] == '-' && p[1] == ch && !p[2])
  124.                                    length = atoi(++p);
  125.                            else
  126.                                    length = atoi(argv[optind] + 1);
  127.                            break;
  128.                    }
  129.            }
  130.  
  131. 4.3 Berkeley Distribution       April 19, 1994                               2
  132.